
=httpRequest:=

The 
[[doc:tpt:http:HTTPBridge|HTTPBridge]] 
inserts a dynamic space into the request scope it uses when issuing
its sub-request into the overlay's wrapped space.
This space resolves requests for identifiers using
the <code>httpRequest:</code> URI scheme.
The <code>httpRequest:</code> 
address space provides information from the external HTTP request that may be retrieved by
issuing requests with the SOURCE verb.
The information is ultimately retrieved from the underlying HTTPRequest object
issued by the HTTP transport.

==Parameter Normalization==

The ''httpRequest:'' space normalizes access to HTTP parameters.  Regardless whether
a parameter is provided as a URL query argument or as a url-encoded value in the POST body,
it will be accessible using the httpRequest:/params, httpRequest:/param/xxxx spaces described below.

POST requests that mix url-encoded fields with URL query parameters are supported and are also unified into the normalized parameter space.

==httpRequest:/params==

Returns an instance of
[[doc:physical:hds:title|IHDSNode]]
as the response representation
which contains the complete set of HTTP request
parameters.

For example, the following HTML will display a form for the user.

{xml}<html>
  <body>
    <p>This page contains various parameters that will be sent to NetKernel</p>
    <form method="POST" enctype="multipart/form-data" action="/test/upload/form">
      Upload File: <input type="file" name="upfile" />
      First Name: <input name="first-name" value="foo" />
      Last Name: <input name="last-name" value="bar"/>
      <input type="submit" value="send file" />
    </form>
  </body>
</html>
{/xml}

If the user selects the file <code>download.png</code> and
enters the text "Johnson" in the <code>last-name</code> field
and the text "Fred" in the <code>first-name</code> field,
then the following code:

{java}public void onSource(INKFRequestContext context) throws Exception
  {
  IHDSNode node = context.source("httpRequest:/params");
  ...	
  }{/java}

will retrieve and IHDSNode with the following information:

{xml}<root>
<upfile>download.png</upfile>
<last-name>Johnson</last-name>
<first-name>Fred</first-name>
</root>
{/xml}


==httpRequest:/param/...==

Returns the HTTP parameter as a {javadocclass}java.lang.String{/javadocclass}
representation.
The form of the identifier is:

{literal}httpRequest:/param/{parameter-name}{/literal}

With the example form shown above, the following code 
retrieves the information the user entered into the field
<code>first-name</code>:

{java}public void onSource(INKFRequestContext context) throws Exception
  {
  String firstName = context.source("httpRequest:/param/first-name");
  ...
  }
{/java}



==httpRequest:/url==

Returns the HTTP URL as a {javadocclass}java.lang.String{/javadocclass}
representation.

The following code retrieves the URL used in the external HTTP request:

{java}public void onSource(INKFRequestContext context) throws Exception
  {
  String url = context.source("httpRequest:/url");
  ...
  }
{/java}



==httpRequest:/header/...==

Returns the specified HTTP header as a {javadocclass}java.lang.String{/javadocclass}
representation.
The form of the identifier is:

{literal}httpRequest:/header/{header-name}{/literal}

For example, the following code retrieves the client's "User-Agent"
header:

{java}public void onSource(INKFRequestContext context) throws Exception
  {
  String userAgent = context.source("httpRequest:/header/User-Agent");
  ...
  }
{/java}

==httpRequest:/headers==

Returns a complete {search}HDSNode{/search} list of all  HTTP header name-value pairs.


==httpRequest:/method==

Returns the HTTP method used in the external HTTP request as a 
{javadocclass}java.lang.String{/javadocclass}
representation.

{java}public void onSource(INKFRequestContext context) throws Exception
  {
  String method = context.source("httpRequest:/method");
  if ("POST".equals(method))
    {
    ...
    }
  ...
  }
{/java}


==httpRequest:/body==

Returns the body of an HTTP POST or PUT request as a
IReadableBinaryStreamRepresentation representation.

{java}public void onSource(INKFRequestContext context) throws Exception
  {
  IReadablBinaryStreamRepresentation body = context.source("httpRequest:/body");
  ...
  }
{/java}


==httpRequest:/upload/...==

Returns an instance of
IReadableBinaryStreamRepresentation
as the response representation
which is the binary contents of the file
selected by the user.
The form of the identifier is:

{literal}httpRequest:/upload/{input-name}{/literal}

For example, the following HTML form allows a user to specify
a local file and uploads it to NetKernel with the name 
<code>upfile</code>:

{xml}
<html>
<body>
<form method="POST" enctype="multipart/form-data" action="/process-file-upload">
       File to upload: <input type="file" name="upfile"/>
<input type="submit" value="send file"/>
</form>
</body>
</html>
{/xml}

The following accessor endpoint code obtains the file as a binary stream:

{java}public void onSource(INKFRequestContext context) throws Exception
  {
  IReadableBinaryStreamRepresentation file;
  file = context.source("httpRequest:/upload/upfile");
  ...
  }
{/java}



==httpRequest:/cookie/...==

Returns an instance of  
{javadoc}javax.servlet.http.Cookie{/javadoc} 
as the response representation;
this object contains the information in the 
[http://en.wikipedia.org/wiki/HTTP_cookie|HTTP Cookie] 
provided in the
external HTTP request.
The form of the identifier is:

{literal}httpRequest:/cookie/{cookie-name}{/literal}


This endpoint code sets a cookie.
The path is explicitly set to "/" so that the browser
returns the cookie for all subsequent requests.
The maximum age of the cookie is set to 60,000 seconds
(if left unset the cookie will expire after the session ends):

{java}public void onSource(INKFRequestContext context)
  {
  ...
  response = context.createResponseFrom(representation);
  ...
  Cookie cookie = new Cookie("rememberthis", "special-value");
  cookie.setPath("/");
  cookie.setMaxAge(60000);
  context.sink("httpResponse:/cookie", cookie);
  }
{/java}

Once set, this same cookie can be retrieved in a subsequent
HTTP request by the following accessor endpoint code:


{java}public void onSource(INKFRequestContext context) throws Exception
  {
  cookie = context.source("httpRequest:/cookie/rememberthis");
  String value = cookie.getValue();
  if("special-value".equals(value)) 
    {
    ...
    }
  ...
  }
{/java}



==httpRequest:/remote-host==

Returns the HTTP remote host name as a {javadocclass}java.lang.String{/javadocclass}
representation.

{java}public void onSource(INKFRequestContext context) throws Exception
  {
  String hostname = context.source("httpRequest:/remote-host");
  ...
  }
{/java}


==httpRequest:/advanced/HttpServletRequest==

Returns the  low-level 
{javadoc}javax.servlet.http.HttpServletRequest{/javadoc} 
object as the response representation.



